package com.aspire.aimini.service;

import com.aspire.aimini.model.dto.TagDTO;
import com.aspire.aimini.model.query.TagQuery;
import com.baomidou.mybatisplus.core.metadata.IPage;

import java.util.List;
import java.util.Map;

/**
 * 标签Service接口
 *
 * @author wangguiyou
 * @date 2024-01-01
 * @description 标签业务逻辑接口
 */
public interface TagService {

    /**
     * 分页查询标签列表
     *
     * @param query 查询条件
     * @return 分页结果
     */
    IPage<TagDTO> getTagPage(TagQuery query);

    /**
     * 根据ID获取标签详情
     *
     * @param id 标签ID
     * @return 标签详情
     */
    TagDTO getTagById(Long id);

    /**
     * 创建标签
     *
     * @param name        标签名称
     * @param category    标签分类
     * @param color       标签颜色
     * @param description 标签描述
     * @param userId      用户ID
     * @return 创建的标签
     */
    TagDTO createTag(String name, String category, String color, String description, Long userId);

    /**
     * 更新标签信息
     *
     * @param id          标签ID
     * @param name        标签名称
     * @param category    标签分类
     * @param color       标签颜色
     * @param description 标签描述
     * @param userId      用户ID
     * @return 更新后的标签
     */
    TagDTO updateTag(Long id, String name, String category, String color, String description, Long userId);

    /**
     * 删除标签
     *
     * @param id     标签ID
     * @param userId 用户ID
     */
    void deleteTag(Long id, Long userId);

    /**
     * 批量删除标签
     *
     * @param ids    标签ID列表
     * @param userId 用户ID
     */
    void batchDeleteTags(List<Long> ids, Long userId);

    /**
     * 根据名称查询标签
     *
     * @param name   标签名称
     * @param userId 用户ID
     * @return 标签信息
     */
    TagDTO getTagByName(String name, Long userId);

    /**
     * 根据分类查询标签列表
     *
     * @param category 标签分类
     * @param userId   用户ID
     * @return 标签列表
     */
    List<TagDTO> getTagsByCategory(String category, Long userId);

    /**
     * 获取热门标签
     *
     * @param limit  限制数量
     * @param userId 用户ID
     * @return 热门标签列表
     */
    List<TagDTO> getPopularTags(Integer limit, Long userId);

    /**
     * 获取最近使用的标签
     *
     * @param limit  限制数量
     * @param userId 用户ID
     * @return 最近标签列表
     */
    List<TagDTO> getRecentTags(Integer limit, Long userId);

    /**
     * 获取系统标签列表
     *
     * @return 系统标签列表
     */
    List<TagDTO> getSystemTags();

    /**
     * 获取用户自定义标签列表
     *
     * @param userId 用户ID
     * @return 自定义标签列表
     */
    List<TagDTO> getCustomTags(Long userId);

    /**
     * 搜索标签
     *
     * @param keyword 关键词
     * @param userId  用户ID
     * @param limit   限制数量
     * @return 标签列表
     */
    List<TagDTO> searchTags(String keyword, Long userId, Integer limit);

    /**
     * 增加标签使用次数
     *
     * @param id 标签ID
     */
    void incrementUseCount(Long id);

    /**
     * 减少标签使用次数
     *
     * @param id 标签ID
     */
    void decrementUseCount(Long id);

    /**
     * 获取未使用的标签
     *
     * @param userId 用户ID
     * @return 未使用标签列表
     */
    List<TagDTO> getUnusedTags(Long userId);

    /**
     * 清理未使用的标签
     *
     * @param userId 用户ID
     * @return 清理数量
     */
    int cleanUnusedTags(Long userId);

    /**
     * 获取标签分类列表
     *
     * @param userId 用户ID
     * @return 分类列表
     */
    List<String> getTagCategories(Long userId);

    /**
     * 按分类统计标签数量
     *
     * @param userId 用户ID
     * @return 统计结果
     */
    List<Map<String, Object>> countByCategory(Long userId);

    /**
     * 获取标签使用统计
     *
     * @param userId 用户ID
     * @return 统计信息
     */
    Map<String, Object> getTagUsageStats(Long userId);

    /**
     * 批量创建标签
     *
     * @param tagNames 标签名称列表
     * @param category 标签分类
     * @param userId   用户ID
     * @return 创建的标签列表
     */
    List<TagDTO> batchCreateTags(List<String> tagNames, String category, Long userId);

    /**
     * 合并标签
     *
     * @param sourceTagId 源标签ID
     * @param targetTagId 目标标签ID
     * @param userId      用户ID
     */
    void mergeTags(Long sourceTagId, Long targetTagId, Long userId);

    /**
     * 检查标签名称是否已存在
     *
     * @param name      标签名称
     * @param userId    用户ID
     * @param excludeId 排除的标签ID
     * @return 是否存在
     */
    boolean checkTagNameExists(String name, Long userId, Long excludeId);
}